This section is adapted from Kate Miller and Sarah Wright’s IMD Training on Version Control
Git is the software needed for this learning session.If you do not already have Git installed on your computer, please install before the session.
If you’re having issues installing Git, consult the R Advisory Group Resources Sharepoint site and submit a helpdesk ticket if needed.
Go to Join Github to get started!
Username example: LpalaciosNPS or sam-olivares-mejia
You will need to verify your email to complete the joining process.
Once verified you will see the screen below. You don’t need to personalize your account right away, click skip to reach your home screen.
Your new home page will look like this
To Do: Once you’ve completed this step Please email your username to Sam (samantha_olivares-mejia@partner.nps.gov) so she can add you to our training github page!
Still having trouble? This Wiki How gives in depth instructions.
usethis packageRemember, to install packages we use the install.packages() function. You can type this in the Console.
Your personal access token is used to connect your Github account to RStudio.
# This opens up a browser window where you can create a personal access token. It may ask you to log into GitHub or confirm your password.
usethis::create_github_token()
gitcreds::gitcreds_set()
Yay! You’ve successfully connected your Github account to Git! Wait I thought Git were the same thing?? Let’s go to the next section and learn about the difference between the two !
Git/Github is a type of version control which is a way to save your progress in an organized manner. It allows you to keep track of your changes every step of the way, and allows for easy collaboration between teams.
Git and Github are used interchangeably, however they are two sperate entities.
Git is the software you install on your computer GitHub is an online interface for storing and collaborating with code.
First we are going to create a branch from main. To do this, go to the SWNC Learning Github Repository.
If you’ve emailed Sam your GitHub username you should have contributor access to the repository.
Click on the main dropdown in the upper left, and begin typing your name separated by underscores. Once complete, click on ‘Create branch:your name from main’. This will create your branch!
Note: Typically we make branches to work on different sections of the code and name them accordingly (ex.’DataWrangling’, ‘Analysis’). This ensures that when developing the code, we are not editing the same sections in different branches at the same time which would create issues in merging the code later on.
To switch to your branch of the repository, navigate to the Git Panel in RStudio. It should be located in the upper right panel next to your environment. If it is not there you can go to View >ShowGit to view it.
Click the drop down menu in the upper right and select your branch name to switch to your branch!
We will create a new markdown file to add to the file structure by clicking file > New File > R Markdown.
When prompted, enter FirstName_LastName as the title of your document. This will auto-poplate the green header block of your file. All other options can be left as defaults. Click OK to create.
RMD files contain example code when they are created.We will keep the top block, but delete everything else (lines 11-30).
Delete the code and replace with your own secret branch message.
Save the changes in the default location (Rstudio will put the file where it is supposed to go) and enter YourFirstName_LastName as the file name.
Navigate to the GIT tab in the upper right. Notice that your RMD file
is now listed, with an ? icon to indicate that it has been modified in
some way. Note that other back-ed files may also be present and can be
ignored for this training.
Click the check box next to your new file. Notice that it is highlighted and the ? icon changes to an “A” for addition. Click the commit button.
A pop-up menu will show you a preview of what you are committing, allowing for you to make a final review.
Notice that the file previous is all green, to indicate additions. Other colors indicate other modifications.
Use the commit message box (requires entry) to describe the changes you have made. Note that anyone with access to the repository will eventually be able to see it.
Once your message is entered, press the commit button at the bottom of the message box.
A wild popup appears!
This popup shows the status of your commit. If you have not configured your username, you may receive a message that Rstudio has automatically attributed your information. This is okay, we’ll use the defaults for now.
What we want to see is the last two lines indicating that a file has been changed and listing your RMD file.
Return to your R studio. In the top left, you should see a note indicating that you have successfully committed a change and are now “ahead”. This means that your version has changes that no one else can see.
But we want Everyone to be able to see your hard work! This is where pushing and pulling comes in.
Pushing means that you take your local changes and throw them into a magical world where everyone can see what you’ve created (GitHub).
Use the green arrow to push your changes. Note that this arrow is in multiple locations in R studio. All accomplish the same thing.
Another popup should appear.
If you have had success, you will see a message like the one below.
Translation of the last line:
you (HEAD) have pushed (->)to the branch (YourFirstName_LastName)
Use your browser to navigate back to our GitHub Repo https://github.com/sam-olivares-mejia/SWNC_Learning_Github
Ensure that you’re on your branch by clicking the branch dropdown menu and selecting your name.
When you change branches, you should be automatically directed to the home screen of the branch. If you were successful, you will see your commit message has been logged and your file now exists online, accessible to others.
Gold Stars if you’ve made it this far!!
To pull data means that you take work that is on GitHub and bring it down locally to edit. (The opposite of pushing)
Pushing and pulling allow for collaboration between individuals in a shared space. For example, Laura can navigate to Sam’s branch, pull her files down, edit her RMD, then push it back so Sam can access the newly changed file.
This is like Sharepoint or OneDrive, but with more commitment. Every time a user pushes changed files to GitHub, the changes are saved, but the old files still remain available as reference.
We will practice pulling and pushing by using another learner’s branch. To avoid confusion from duplication, we will assign each of you a partner’s branch to pull from. See the chat for your assignment.
Navigate to your user’s branch using the branch dropdown menu (same as before). Make sure that you can see their RMD file. If you cannot, please let us know.
Now we’ll change our branch in R studio. Click the dropdown menu (likey populated with FirstName_LastName, indicating the branch you created.)
From the dropdown menu, click your partner’s name.
As we learned earlier, a merge is used to combine your branches commits with main.
When you’re ready to merge the changes you made on your branch to the main, navigate to your branch’s page on github. There will be a section on this page that tells you the status of your branch compared to the main.
In the example above, our branch is 3 commits ahead, and 18 commits behind the main.This tells you that there are 3 changes your branch has that the Main doesn’t have, and 18 commits the main has that your branch doesn’t. Typically, your branch will have more commits ‘ahead’ vs ‘behind’ the main.
Below is an example to help visualize branches being ‘ahead’ or ‘behind’ the main.
To begin the merge process, click on the hyper linked text telling you how many commits ahead or behind your branch is. This will lead you to a Comparing Changes page.
Lets break down this page.
Outlined in red, is the part of the page that tells you what branches you’re comparing, and whether they are able to be merged automatically. In this example, the green text Able to Merge tells us that there are no merge conflicts that would cause issues during the merge.
Outlined in blue, is a summary of the commits in the branch. You can see how many commits were made, how many files were changed, and who contributed to the branch. Additionally you can also see the commit messages and the date they were each committed.
Emphasized in green, is the create pull request button. Clicking this button will begin the review process to merge your branch into the main!
GitHub will lead you to the open a pull request page. Here you can write messages to your collaborators letting them know you’d like to merge the branch into the main and elaborate on the branch’s changes. Once you’re ready to submit the request, click the create pull request button again.
The final page before merging allows you to review the proposed merge with your collaborators. The conversation tab gives you a summary of the changes made, the ability to finalize the merge via the merge pull request button, and a place to add more comments or close the pull request. There are also other tabs that go into more detail on the commit and change history of your branch.
In a typical workflow, collaborators would discuss the commit history of the branch together before merging to the main to avoid confusion and merge conflicts.
Congrats! We have made it to the end of today’s session :) We know that github can be a bit confusing conceptually, but we hope you can use this workbook and the resources below to help you reference problems in the future! We will also be hosting our next R Work session December 21 from 1-3pm to go over more questions or issues!
If you’re having trouble installing packages and are getting an error related to the ‘CRAN server’, you may need to change your CRAN mirror settings. This seems to be an issue with folks who have recently installed R and using the the 4.2.0 version.
Navigate to Tools>Global Options>Packages. Click the Change button next to Primary CRAN repository, and switch to ‘USA (TX1)…Dallas’. Once selected, click ‘Apply’ and ‘OK’. This should fix the issue and allow you to install packages smoothly.